Introduction

Creating a website with Txt2Site is easy. You can build a simple website in a one minute - using only a few features. You can then add things as you need them.

This tutorial explains the basics of creating a website.

A Basic Site

The principles of Txt2Site are simple. A Txt2Site application has at least the following elements:

1. a configuration file.

This tells Txt2Site where to read files from (the content directory), and where to put the files it creates (the target directory).

2. a template file.

This is the HTML template file for your website.

3. a content file.

This is the content file for a page. Each content directory optionally has one or more content files.

Txt2Site generates for each content file a HTML page based on the template file.

Creating a Demo Site

Ok - so let's see how this works in practice.

The first thing we'll do is create a default environment for a sample application. Txt2Site makes it easy for you.
The next command generates a default environment for a sample application called my_demo.

  $ txt2site -n my_demo 

This command with option -n (new) creates a file structure for the application in the working directory which look like this:

   my_demo
     my_demo.conf 
     content
          default 
     include
          css
             style.css 
     site
          target
     templates
          template 

A root directory called my_demo is created in the working directory. All files and directories of the application are created in this root directory. Locations indicated by red are files.
The files my_demo.conf, default, style.css and template are created with system defined content. Verify that the settings for the directory structure in the config file agree with the generated directories. Look at these lines in the config file my_demo.conf.

• content_dir=content
• include_dir=include
• target_dir=site/target
• template_dir=templates
• style_dir=include/css

All paths in the config file are relative to the root directory. This ensures that no files are created outside the root directory.
The HTML page files of the application are created in the site directory. Up to now the site directory is empty. Based on the generated files so far, a website can be generated by executing the next command:

  $ txt2site  -g  my_demo/my_demo.conf 

The command with option -g (generate) has the config file as argument. The path of the config file is relative to the working directory. If the config file not exists, the command finishes with an error message. After executing succesful a website is created in the site directory (more exactly: in the site/target directory).

The include directory is used for stylesheets and images. Txt2Site copies the include directory to the target directory of the website.

Page generated by Txt2Site. Execute the file site/target/index.html in your browser to view the created webpage.

Notice that the base color of the demo website is by default green. You can generate a website with a different color. Use the name of the color in the name of the site. For example if you call it my_demo_red, then the color will be red. You can define five colors:

red	green	blue	yellow	grey

Extending the Demo Site

Content files

Open the file default in the content directory with a text editor. Look at different parts of the file.

     VARIABLE SECTION
       variable=value
       variable=value
       ...
  
     <<<<< content section 1 >>>>>
  
       content text of section 1 (HTML format)
  

After the section delimiter you can specify the content for the first section. If you want you can define more than one content section. The format for the generated demo is set to HTML. Other markup languages are available.

Exercise 1:

Exercise 2:

Look at the result. It stands out that the horizontal menu at the top is changed. The new page is now visible. The menu is generatad by Txt2Site. You can see how this works by looking at the template file. The template file contains a div called div_hormenu. The HTML content of this div is created by the builtin function $(html_mainmenu_div).
What you learn is that calling a builtin function you specify $(function_name). When you want to display variables, you use curly brackets and specify ${variable_name}. See the user manual for a list of builtin functions you can use.
You can also use bash functions in the text.
For example use $(date) to get: today is za mrt 15 08:56:06 CET 2014 .

Content subdirectories

Exercise 3:

As expected the navigation menu on the site is changed. The new directory with the two pages are now visible as a new category in the menu. Notice that spaces in the names are allowed. The filenames of the website are deduced from the names of the content files and directories and translated to websafe names.

Exercise 4:

Try to find out the difference between the navigation menus from this and the previous exercise.

Exercise 5:

The effect of the prefixes before the name of content files and content directories is that the order of menu items is changed according to these prefixes. The prefixes are not visible on the site! Prefixes for sorting have a fixed length and format: 999_

Exercise 6:

The im.jpg image is displayed on the website. The path_to_root variable is a system variable that computes the relative path from the current page to the root directory. From there the image is located in the include/images/ directory.